home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / lbmake.doc < prev    next >
Text File  |  1994-02-13  |  7KB  |  187 lines
  1.  
  2. lbmake/lbmake                            lbmake/lbmake
  3.  
  4.                   LBMAKE.DOC
  5.  
  6.             SECOND GENERATION LINK LIBRARY MANAGER
  7.  
  8.     The LBMake utility is similar to LibMake but greatly enhances your
  9.     ability to manage the compiling of link libraries from source code. The
  10.     LBMake utility uses a control file called "lib.def" in the directory
  11.     you run lbmake from.  For a good example of a fully working LBMake
  12.     system refer to the LIB.DEF file in the DCC:LIB/ directory (containing
  13.     the full compilable library source to DICE).
  14.  
  15.     LBMake understands the basics of compiling source files into objects
  16.     and JOINing objects into libraries as well as how to turn .FD files
  17.     into tag libraries.  LBMake is used to generate all of DICE's
  18.     link libraries and object modules.
  19.  
  20.     The LBMake control file, "lib.def" determines LBMake's operation in
  21.     conjuction with keywords you give it.  The control file may contain
  22.     lines of the following form:
  23.  
  24.     @Type   <symbol>    <options>
  25.  
  26.     The @Type command associates a set of compiler options with a
  27.     symbol.  For example:
  28.  
  29.     @Type    s        -ms -r -pr
  30.  
  31.     You normally have several @Type commands denoting various memory
  32.     models you wish to generate libraries for.  When you run LBMake,
  33.     any keywords you specify on the command line which match symbols
  34.     specified in @Type commands will cause the associated options to
  35.     be used when compiling source files.  By specifying several keywords
  36.     on the LBMake command line you can merge options for several
  37.     memory model combinations.
  38.  
  39.     The @Type symbols are merged together to create a single symbol
  40.     which can be used to modify the name of the generated library
  41.     or object module.
  42.  
  43.     @Objects <symbol> <filepath>
  44.  
  45.     The @Objects command defines a symbolic name which will later be
  46.     used to reference individual files that are to be compiled into
  47.     individual object modules.  The <filepath> contains the filename
  48.     template that is to be used to name the object files after
  49.     compilation, where %s denotes the name of the object module.
  50.     For example:
  51.  
  52.     @Objects startup    dlib:%s
  53.  
  54.     If, later on, the 'startup' symbol is associated with the files
  55.     fubar/a.c, fubar/b.c, and fubar/c.c LBMake will, when asked to
  56.     compile 'startup', generate the object modules dlib:a.o, dlib:b.o,
  57.     and dlib:c.o from their source files.
  58.  
  59.     You may specify multiple @Objects commands but should specify at
  60.     most one @Objects reference at a time on the LBMake command line,
  61.     as in the example above.
  62.  
  63.     @Library <symbol> <filepath>
  64.  
  65.     The @Library commands is similar to the @Objects command but
  66.     indicates that all files referenced by <symbol> are to be
  67.     JOIN'd together into a single result.  For example:
  68.  
  69.     @Library    clib    dlib:c%s.lib
  70.  
  71.     The filename template in this case reflects any @Type commands
  72.     which you have activated via the LBMake command line.  For
  73.     example, if you ran the following LBMake:
  74.  
  75.     1> LBMake s r clib
  76.  
  77.     LBMake would commence to compile objects associated with the 'clib'
  78.     symbol, JOIN them together, and name the result 'dlib:csr.lib'.
  79.  
  80.     You may specify multiple @Library commands but should specify at
  81.     most one @Library reference at a time on the LBMake command line,
  82.     as in the example above.
  83.  
  84.     @DefTree    <filepath>
  85.  
  86.     The @DefTree command defines the default DIRECTORY where
  87.     intermediate files are to be stored.  The name of the directory
  88.     can depend on the @Type commands which have been activated
  89.     thereby giving you separate directories for separate memory
  90.     models.
  91.  
  92.     @DefTree    dtmp:comp3/lib_%s/
  93.  
  94.     So, for example, if you were to 'LBMake s r clib' LBMake would put
  95.     the associated object modules in 'dtmp:comp3/lib_sr/'.
  96.  
  97.     @AltTree    <symbol>    <filepath>
  98.  
  99.     The @AltTree command works like @DefTree but allows you to specify
  100.     a symbol on the LBMake command line which overides the @DefTree.
  101.  
  102.     @AltTree    pass2   dtmp:comp2/lib_%s/
  103.  
  104.     You may specify multiple @AltTree commands but should specify at
  105.     most one on the LBMake command line.  This feature is most useful
  106.     in a production system to generate 'experimental' versions of a
  107.     library until one is ready for the next release, then generate a
  108.     'master' version.
  109.  
  110.                 SPECIFYING FILES
  111.  
  112.     The remainder of the "lib.def" control file contains file
  113.     specifications.. i.e. a list of files and which libraries they
  114.     apply to.  A file can apply to more then one library.  The general
  115.     format for the file list is:
  116.  
  117.     <filename>            +/-<symbol> +/-<symbol> +/-<symbol> ...
  118.  
  119.     Each file is followed by one or more symbols.  For example:
  120.  
  121.     amiga/profile.c    +clib +uclib +free -pass2
  122.  
  123.     Would indicate that the amiga/profile.c module is associated with the
  124.     library defined by the symbol 'clib', the library defined by the symbol
  125.     'uclib', and the library defined by the symbol 'free' (i.e. these three
  126.     symbols are part of @Library commands).  However, the file does not
  127.     exist in any of these libraries of the 'pass2' symbol is specified on
  128.     the Command line, where 'pass2' also refers to an @AltTree command.
  129.  
  130.     The basic idea is that you list every file for every library in a
  131.     particular project, just as I have done in my "lib.def" file for DICE,
  132.     then use LBMake to generate the actual .lib and .o files.
  133.  
  134.     LBMake will create a duplicate directory structure in the object tree
  135.     as specified by @DefTree (or an active @AltTree).  It appends the
  136.     FULL PATH of the source file to the destination tree so, for example,
  137.     if you were to:
  138.  
  139.     1> LBMake s r clib
  140.  
  141.     The LBMake would compile 'amiga/profile.c' into
  142.     'dtmp:comp3/lib_sr/amiga/profile.o'
  143.  
  144.     Therefore, you may not specify any absolute file paths in order for
  145.     LBMake to work properly.
  146.  
  147.  
  148.                 .FD FILES
  149.  
  150.     LBMake supports the generation of tag libraries from .FD files.  It
  151.     recognizes a .FD file by the .FD extension in the file specification.
  152.     In order to properly support .FD files LBMake requires that the
  153.     file specification be of the following form:
  154.  
  155.     [directory_path]filename_lib.fd     +/-<symbol> +/-<symbol> ...
  156.  
  157.     Why the brackets?  Well, remember what I said about not being able to
  158.     use absolute filepaths because they screw up the placement of object
  159.     modules in the object tree?  Brackets provide a solution to this
  160.     problem when you have no choice but to use absolute file paths. The
  161.     part of the path in brackets will be IGNORED when it comes to figuring
  162.     out what the object file name should be.  This is especially important
  163.     for .FD files which are generally put elsewhere.
  164.  
  165.     To further automate operation LBMake looks for the prototype file
  166.     associated with the .FD file using the same path but munging the
  167.     '_lib.fd' part to '_protos.h' and munging '/fd/' or ':fd/' into
  168.     '/clib/' or ':clib/'.  In otherwords, it munges something like:
  169.  
  170.     [dinclude:amiga20/fd/]mathieeesingbas_lib.fd     into
  171.     [dinclude:amiga20/clib/]mathieeesingbas_protos.h
  172.  
  173.                 AUTOINIT CODE INCLUSION
  174.  
  175.     For autoinit code inclusion one needs to specify the actual
  176.     name of the library, e.g. 'fubar.library', along with each .FD file
  177.     name using the following format:
  178.  
  179.     [directory_path]filename_lib.fd,libraryname    +/-<symbol> +/-<symbol> ...
  180.  
  181.     For example:
  182.  
  183.     h/fd/myfubar_lib.fd,fubar.library   +mylib
  184.  
  185.  
  186.  
  187.